Docs V2: new information architecture (CIP-3307) by coderdan · Pull Request #37 · cipherstash/docs

coderdan · 2026-07-02T07:24:20Z

Long-lived integration branch for the docs V2 overhaul, tracked in CIP-3307. Opened as a draft — it merges only when the migration completes (CIP-3335); section work stacks as PRs targeting this branch, and this PR's Vercel preview is the staging site for the whole overhaul.

What's in the scaffold (CIP-3325)

IA.md — living migration checklist at the repo root: one checkbox per planned page, ticked as sections land, with the branch's working rules (how to move a page, redirect flag, URL conventions)
New v2docs collection (content/docs) served from the site root (/docs/get-started/…, /docs/integrations/supabase, …) via a required catch-all route. The legacy tree still serves at /docs/stack/* — both trees coexist until every section migrates, then the legacy tree is deleted
Frontmatter facet model: Diátaxis type, components, audience, integration (category / setup / pairsWith), and review-tracking fields (verifiedAgainst, reviewBy)
All 8 sections scaffolded with nav + stubs, including /docs/integrations/supabase (the Supabase listing's link target)
v2-redirects.mjs — full legacy→v2 map (85/85 pages covered), gated behind ENABLE_V2_REDIRECTS=1 so previews serve both trees during migration; the flag flips on at merge. bun run validate-redirects is wired into prebuild: a legacy page without a mapping fails CI
/docs/quickstart vanity redirect (ungated — no legacy traffic on that path)
llms.txt / llms-full.txt / sitemap / .mdx raw-markdown mirror all cover the v2 tree (listed first)
Removed the AI-citation redirect /reference/eql → /stack/reference/eql — its source collided with (and shadowed) the v2 page at that path

How to review the preview

New tree: /docs/get-started, /docs/integrations/supabase, /docs/security/compliance, /docs/reference/eql (stubs for now)
Legacy tree unchanged: /docs/stack/quickstart etc.
Agent surface: append .mdx to any v2 page URL; /docs/llms.txt

Merge checklist (CIP-3335, end of migration)

All IA.md sections ticked; every redirect destination resolves
ENABLE_V2_REDIRECTS=1 set for production
content/stack, /stack routes, and the legacy loader deleted
Final consistency sweep + Supabase listing revision

https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Foundation for the docs overhaul tracked in CIP-3307: - IA.md: living migration checklist at the repo root (one checkbox per planned page; sections tick off as they land on this branch) - New `v2docs` collection (content/docs) served from the site root via a required catch-all route, alongside the legacy tree (content/stack) at /stack until every section migrates - Frontmatter facet model: Diátaxis `type`, `components`, `audience`, `integration` (category / setup / pairsWith), and review-tracking fields (`verifiedAgainst`, `reviewBy`) - Section scaffold: get-started, integrations (incl. the /integrations/supabase stub the Supabase listing links to), concepts, compare, guides, security, solutions, reference — meta.json + stubs - v2-redirects.mjs: full legacy→v2 map (85/85 pages covered), gated behind ENABLE_V2_REDIRECTS=1 so the preview serves both trees during migration; /quickstart vanity redirect ships ungated - scripts/validate-v2-redirects.ts wired into prebuild: CI fails if a legacy page has no v2 mapping - llms.txt, llms-full.txt, sitemap, and the .mdx raw-markdown mirror now cover both trees Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

…rence/eql Two issues caught by smoke-testing the scaffold: - Stub descriptions containing ":" broke YAML frontmatter parsing (500s across the v2 tree) — descriptions are now quoted. - The AI-citation redirect "/reference/eql" → "/stack/reference/eql" shadowed the v2 /reference/eql page (redirects run before the filesystem); removed since the v2 page now serves that path. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

vercel · 2026-07-02T07:24:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
public-docs	Ready	Preview, Comment	Jul 2, 2026 12:33pm

…t bare root Two fixes from preview review: - The bare domain root (Vercel preview URLs) 404'd because the app lives under the /docs basePath — added a basePath:false redirect / → /docs. In production only /docs/* reaches this app, so previews-only. - The /docs landing was a standalone (home) page disconnected from the v2 nav, with every link pointing at legacy /stack URLs. It's now content/docs/index.mdx rendered inside DocsLayout (sidebar + search), linking the v2 sections. The catch-all became optional ([[...slug]]) and the (home) route group is deleted (recoverable from history; CIP-3327 refines the landing content). - The landing's raw-markdown mirror serves at /docs/index.mdx (its URL is "/", which can't carry the .mdx suffix). Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Listing "index" explicitly in meta.json pages forced each section's index out as a separate child item with the same title as its folder (clicking "Get started" opened a sub-nav containing another "Get started"). With index unlisted, Fumadocs merges it into the folder row: the folder itself links to the page, and children are only real sub-pages (Integrations → Supabase, not Integrations → Integrations). The root meta.json keeps "index" — at tree root there is no folder row to merge into, so the landing needs its own sidebar item. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Folders whose only page is their index still rendered as collapsible sidebar folders with a chevron pointing at nothing. getV2PageTree() now collapses such folders into plain page items (recursively, so guides/* and reference/* leaves flatten too); a section becomes a folder again automatically when its first real sub-page lands. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

MDX links (markdown and Card hrefs) render through the Link component, which prefixes the /docs basePath — hardcoded /docs/... links rendered as /docs/docs/... and 404'd. Convention (enforce via CIP-3349 lint): internal links in content are always basePath-relative. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Copilot

Pull request overview

This PR scaffolds the “Docs V2” information architecture by introducing a new content/docs tree served from the site root (under the existing /docs basePath), while keeping the legacy content/stack tree available at /docs/stack during migration. It also adds a gated legacy→v2 redirect map plus CI validation to ensure legacy pages won’t become orphaned when redirects are enabled.

Changes:

Add a new v2docs collection + v2source loader, plus root catch-all routes/layout for the v2 docs tree.
Introduce a full legacy→v2 redirect map (v2-redirects.mjs) gated by ENABLE_V2_REDIRECTS=1, with a prebuild validation script to enforce coverage.
Scaffold v2 section stubs/meta and update sitemap + LLM surfaces (llms.txt, llms-full.txt, .mdx raw mirror) to include the v2 tree first.

Reviewed changes

Copilot reviewed 65 out of 65 changed files in this pull request and generated 25 comments.

Show a summary per file

File	Description
v2-redirects.mjs	Adds the full legacy `/stack/*` → v2 redirect mapping list (flag-gated in Next config).
next.config.mjs	Wires in gated v2 redirects, adds preview root redirect, and adds `.mdx` rewrite for v2 raw mirror; removes old `/reference/eql` redirect collision.
scripts/validate-v2-redirects.ts	Adds CI/prebuild gate to ensure every legacy `content/stack` page is covered by v2 redirects.
package.json	Adds `validate-redirects` script and runs it during `prebuild`.
source.config.ts	Defines the new `v2docs` collection and its frontmatter facet schema.
src/lib/source.ts	Adds `v2source`, v2 page tree shaping (`flattenEmptyFolders`), and broadens `getLLMText` typing for both trees.
src/app/[[...slug]]/layout.tsx	Adds the v2 docs layout (DocsLayout + v2 tree) at the root catch-all segment.
src/app/[[...slug]]/page.tsx	Adds the v2 docs page renderer, metadata generation, and markdown mirror URL generation.
src/app/llms.mdx/v2/[[...slug]]/route.ts	Adds the v2 raw-markdown mirror route for agent/LLM consumption.
src/app/llms.txt/route.ts	Lists v2 pages first, then legacy pages, in `llms.txt`.
src/app/llms-full.txt/route.ts	Emits the concatenated markdown for v2 pages first, then legacy pages.
src/app/sitemap.ts	Includes both v2 and legacy pages in sitemap (v2 first).
src/app/og/docs/[...slug]/route.tsx	Import ordering tweak only.
src/app/api/search/route.ts	Import ordering tweak only.
src/app/layout.tsx	Import ordering tweak only.
src/app/stack/layout.tsx	Import ordering tweak only.
src/app/stack/[[...slug]]/page.tsx	Import ordering tweak only.
src/proxy.ts	Import ordering tweak only.
src/lib/posthog/provider.tsx	Import ordering tweak only.
src/components/icons/supabase.tsx	Fixes missing semicolon in return statement.
src/app/(home)/page.tsx	Removes the standalone legacy docs landing page implementation.
src/app/(home)/layout.tsx	Removes the legacy home layout wrapper.
IA.md	Adds the migration checklist + branch workflow rules for the v2 overhaul.
content/docs/meta.json	Adds v2 root meta defining top-level section ordering.
content/docs/index.mdx	Adds the v2 docs landing page content (Cards + LLM surface links).
content/docs/get-started/meta.json	Adds v2 “Get started” section meta.
content/docs/get-started/index.mdx	Adds v2 “Get started” stub page.
content/docs/integrations/meta.json	Adds v2 “Integrations” section meta.
content/docs/integrations/index.mdx	Adds v2 “Integrations” stub page.
content/docs/integrations/supabase/meta.json	Adds v2 Supabase integration meta (custom icon).
content/docs/integrations/supabase/index.mdx	Adds v2 Supabase stub page with facet example.
content/docs/concepts/meta.json	Adds v2 “Concepts” section meta.
content/docs/concepts/index.mdx	Adds v2 “Concepts” stub page.
content/docs/compare/meta.json	Adds v2 “Comparisons” section meta.
content/docs/compare/index.mdx	Adds v2 “Comparisons” stub page.
content/docs/guides/meta.json	Adds v2 “Guides” section meta.
content/docs/guides/index.mdx	Adds v2 “Guides” stub page.
content/docs/guides/development/meta.json	Adds v2 “Development” guides meta.
content/docs/guides/development/index.mdx	Adds v2 “Development” stub page.
content/docs/guides/migration/meta.json	Adds v2 “Data migration” guides meta.
content/docs/guides/migration/index.mdx	Adds v2 “Data migration” stub page.
content/docs/guides/deployment/meta.json	Adds v2 “Deployment” guides meta.
content/docs/guides/deployment/index.mdx	Adds v2 “Deployment” stub page.
content/docs/guides/troubleshooting/meta.json	Adds v2 “Troubleshooting” guides meta.
content/docs/guides/troubleshooting/index.mdx	Adds v2 “Troubleshooting” stub page.
content/docs/security/meta.json	Adds v2 “Architecture & security” section meta.
content/docs/security/index.mdx	Adds v2 “Architecture & security” stub page.
content/docs/security/compliance/meta.json	Adds v2 “Compliance” meta under security.
content/docs/security/compliance/index.mdx	Adds v2 “Compliance” stub page.
content/docs/solutions/meta.json	Adds v2 “Solutions” section meta.
content/docs/solutions/index.mdx	Adds v2 “Solutions” stub page.
content/docs/reference/meta.json	Adds v2 “Reference” section meta.
content/docs/reference/index.mdx	Adds v2 “Reference” stub page.
content/docs/reference/eql/meta.json	Adds v2 “EQL” reference meta.
content/docs/reference/eql/index.mdx	Adds v2 “EQL” stub page.
content/docs/reference/stack/meta.json	Adds v2 “Stack SDK” reference meta.
content/docs/reference/stack/index.mdx	Adds v2 “Stack SDK” stub page.
content/docs/reference/proxy/meta.json	Adds v2 “Proxy” reference meta.
content/docs/reference/proxy/index.mdx	Adds v2 “Proxy” stub page.
content/docs/reference/cli/meta.json	Adds v2 “CLI” reference meta.
content/docs/reference/cli/index.mdx	Adds v2 “CLI” stub page.
content/docs/reference/auth/meta.json	Adds v2 “Auth” reference meta.
content/docs/reference/auth/index.mdx	Adds v2 “Auth” stub page.
content/docs/reference/workspace/meta.json	Adds v2 “Workspace & account” reference meta.
content/docs/reference/workspace/index.mdx	Adds v2 “Workspace & account” stub page.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+  <Card title="Integrations" href="/docs/integrations" description="Platforms, ORMs, frameworks, auth providers, and runtimes." />
+  <Card title="Concepts" href="/docs/concepts" description="How searchable encryption, key management, and identity-aware encryption work." />
+  <Card title="Guides" href="/docs/guides" description="Development workflow, data migration, deployment, and troubleshooting." />
+  <Card title="Architecture & security" href="/docs/security" description="Trust model, components, availability, audit, and compliance — for security review." />
+  <Card title="Solutions" href="/docs/solutions" description="PII protection, HIPAA, AI/RAG, data residency, and provable access." />


+  <Card title="Guides" href="/docs/guides" description="Development workflow, data migration, deployment, and troubleshooting." />
+  <Card title="Architecture & security" href="/docs/security" description="Trust model, components, availability, audit, and compliance — for security review." />
+  <Card title="Solutions" href="/docs/solutions" description="PII protection, HIPAA, AI/RAG, data residency, and provable access." />
+  <Card title="Reference" href="/docs/reference" description="EQL, the Stack SDK, Auth, the CLI, and Proxy — precise API documentation." />


+- **Moving a page = ** move the file into `content/docs`, update its facets,
+  fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here.


Seven pages replacing the v2-era EQL reference, written against the eql_v3 branch of cipherstash/encrypt-query-language (3.0.0): - index: what EQL is, the v3 domain-variant model, install (single SQL script, idempotent), dbdev, Docker, migration/runtime permission split, managed-Postgres rationale - types: 10 scalar families × variants matrix; bool storage-only; _ord/_ord_ore twins; index terms per variant - operators: per-variant support matrix, typed-operand rule, no-LIKE, fail-loud blockers, query shapes, function-form equivalents - indexes: functional indexes on term extractors, engagement requirements, sort-key form for index-streamed ORDER BY, EXPLAIN checklist, large-table build guidance - json: ste_vec model, per-node-type terms (hm XOR oc), containment + GIN, field access, path queries, blocked native jsonb operators - functions: comparisons, extractors, min/max only (no SUM/AVG), version() - payload-format: v/i/c envelope (wire version still v:2), hm/ob/bf term keys, sv document shape, annotated examples (absorbs the legacy CipherCell page) Cross-page consistency verified against the shipped SQL: equality on _ord variants compares ORE terms (no hm in _ord payloads), and bare ORDER BY is correct but extractor-form sort keys stream from the index. Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

coderdan · 2026-07-02T09:13:39Z

+  {
+    source: "/stack/quickstart",
+    destination: "/get-started/quickstart",
+    permanent: true,


We shouldn't make these permanent for now.

Done in d0ccd7e — all 71 entries flipped to permanent: false, with a header note to revisit as part of CIP-3335 once the map has soaked post-merge.

EQL is an abstraction over SQL the way Tailwind is over CSS — the docs now follow the same shape: Install → Core concepts → type categories → Indexes → query patterns, increasing in complexity. Each type-category page is the complete reference for its types (variants, payload shape, operators/functions, example queries on one page). - index: trimmed to the Install page - core-concepts (new): the canonical home for shared mechanics — variant model, payload anatomy (v/i/c envelope + hm/ob/bf terms, absorbs payload-format/CipherCell), typed-operand rule, fail-loud blockers, ORE-equality on _ord, term-leakage pointer - numbers-and-dates, text, booleans (new) + json (reworked): category pages; text owns the no-LIKE treatment; json absorbs the sv payload shape; booleans framed as "every type has a storage-only variant — for bool it's the only one" - filtering, sorting, grouping-and-aggregates, joins (new): cross-type query patterns; joins headlines the same-keyset constraint - deleted: types.mdx, operators.mdx, functions.mdx, payload-format.mdx (content redistributed; URLs never shipped publicly, no redirect debt) - Anti-drift rule recorded in IA.md: mechanics live ONLY in core-concepts; category/query pages link, never restate - meta.json: flat URLs with ---Types---/---Indexes---/---Queries--- sidebar separators; legacy redirect map retargeted (queries → filtering, cipher-cell → core-concepts) Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

…load v:3 Review feedback on the EQL section: - Variant tables: generic form first, then full enumeration of every concrete domain name (Tailwind-style); capability column made concise; "index term carried" column dropped — term internals live in core-concepts' payload anatomy - SEM specifiers documented as a concept in core-concepts: a trailing mechanism suffix (_ord_ore) pins WHICH searchable-encryption mechanism implements a capability; _ord tracks the default (currently ORE). Replaces the "twins" framing. Each orderable type page lists its specifiers under an "SEM specifiers" heading, noting the OPE specifier arriving for all orderable types (incl. text) in the v3 release - Payload `v` field documented as the EQL version (3) per team decision 2026-07-02; all payload examples updated from v:2 Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

…perators and Functions Review feedback: - Dates & times split out of Numbers — same traits, distinct semantics; each page's examples now match its domain (payroll vs audit-event time windows / retention cutoffs / newest-first) - CREATE TABLE examples get an explicit "Example" sub-heading + lead-in - Operators and Functions are separate sections on every type page — operators as the per-variant support matrix, functions as the form-equivalents table (+ MIN/MAX, which only exist as functions) - IA.md: split reflected; query-performance follow-up added (CIP-3351 — the v3 branch already folded the v2 perf guide into database-indexes.md, which our indexes page absorbed) Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

- indexes.mdx: cast query-shape example params to their EQL domain types, consistent with the typed-operand rule - numbers/dates-and-times/text: the fail-loud note now scopes to operators — ORDER BY on a variant without an ordering term doesn't raise, it silently returns a meaningless order (links Sorting)

- v2-redirects.mjs: all entries permanent: false while the IA settles (per review); flip to permanent post-merge soak (CIP-3335) - IA.md: fix unmatched bold around 'Moving a page' - add placeholder pages for /concepts/searchable-encryption (CIP-3333) and /guides/troubleshooting/query-performance (CIP-3351) so the EQL reference's forward links resolve instead of 404ing

# Conflicts: # v2-redirects.mjs

coderdan · 2026-07-02T12:12:04Z

Review comments addressed in d0ccd7e:

/docs/-prefixed links (Copilot, ~20 comments): already fixed in 8514932 (fix(v2): make all MDX links basePath-relative) — those comments predate it. CIP-3349 adds the lint to prevent regressions.
Redirects: all entries now permanent: false; flip tracked under CIP-3335.
IA.md: unmatched-bold fix.
Added placeholder pages for /concepts/searchable-encryption (CIP-3333) and /guides/troubleshooting/query-performance (CIP-3351) so forward links from the EQL reference resolve.

Docs V2: EQL v3 reference section, Tailwind-shaped (CIP-3326)

coderdan added 2 commits July 2, 2026 17:17

vercel Bot deployed to Preview July 2, 2026 07:44 View deployment

docs(v2): note landing-page state in IA.md checklist

5c34cef

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

vercel Bot deployed to Preview July 2, 2026 07:46 View deployment

vercel Bot deployed to Preview July 2, 2026 07:55 View deployment

vercel Bot deployed to Preview July 2, 2026 08:34 View deployment

coderdan requested a review from Copilot July 2, 2026 08:40

Copilot started reviewing on behalf of coderdan July 2, 2026 08:40 View session

vercel Bot deployed to Preview July 2, 2026 08:42 View deployment

Copilot AI reviewed Jul 2, 2026

View reviewed changes

coderdan mentioned this pull request Jul 2, 2026

Docs V2: EQL v3 reference section, Tailwind-shaped (CIP-3326) #38

Merged

coderdan commented Jul 2, 2026

View reviewed changes

coderdan added 7 commits July 2, 2026 19:56

docs(v2): track EQL 3.0.0 release-alignment gate in IA.md (CIP-3352)

123a544

Claude-Session: https://claude.ai/code/session_01ACPpFPHvKtrV48nbEYuv7P

Merge v2 review fixes (placeholder pages, non-permanent redirects)

5e5641c

# Conflicts: # v2-redirects.mjs

vercel Bot deployed to Preview July 2, 2026 12:10 View deployment

Merge pull request #38 from cipherstash/cip-3326-eql-v3-reference

19a132b

Docs V2: EQL v3 reference section, Tailwind-shaped (CIP-3326)

vercel Bot deployed to Preview July 2, 2026 12:33 View deployment

coderdan mentioned this pull request Jul 2, 2026

Docs V2: Supabase integration section + canonical encryptedSupabase reference (CIP-3328) #39

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Docs V2: new information architecture (CIP-3307)#37

Docs V2: new information architecture (CIP-3307)#37
coderdan wants to merge 16 commits into
mainfrom
v2

coderdan commented Jul 2, 2026

Uh oh!

vercel Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderdan Jul 2, 2026

Uh oh!

coderdan Jul 2, 2026

Uh oh!

coderdan commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- Moving a page = move the file into `content/docs`, update its facets,
		fix inbound links, confirm its `v2-redirects.mjs` entry, tick it here.

Uh oh!

Conversation

coderdan commented Jul 2, 2026

What's in the scaffold (CIP-3325)

How to review the preview

Merge checklist (CIP-3335, end of migration)

Uh oh!

vercel Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderdan Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

coderdan Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

coderdan commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented Jul 2, 2026 •

edited

Loading